feat(admin): localize the operator app with react-i18next (3/4) - #1383

Carries two infrastructure fixes that are not this PR's topic. Without them CI cannot even reach this PR's code.

• Dependency bump: Microsoft.SourceLink.GitHub to 10.0.401 and Testcontainers to 4.14.0, clearing NU1902/NU1903 so restore succeeds. Those are the versions #1375 (SourceLink) and #1369 (Testcontainers) carry: this hunk is the union of the two, plus one comment per pin naming the advisory it answers.
• MinIO (c6a72df1): minio/minio is gone from Docker Hub, so every Testcontainers-backed integration test dies on the image pull. Pulls from quay.io on a pinned tag instead. Same fix as #1388.

The MinIO hunk is byte-identical to #1388. The dependency hunk is not byte-identical to #1375 or #1369, which each carry half of it without the comments, but it is identical across all twelve PRs in this series: src/Directory.Packages.props resolves to the same blob (854deb95) at every head. Either way they merge in any order, and these copies can be dropped once the PRs that own them land.

Reopened from #1362. That PR was closed automatically on 2026-09-14, when the head fork
was deleted. It reopened at a10d3976, and review has added commits on top since then (the
commit list above is the current one). The earlier review history stays on #1362.

clients/admin slice of the i18n work, split out of #1344. 111 files, of which 30 are JSON catalogs. Mostly mechanical, as you predicted.

Depends on #1381 for server-side persistence. The switcher works on its own — i18next persists the choice in localStorage — but the locale field this slice sends on PUT /identity/profile is only accepted once #1381 adds it to FshUser, UserDto and UpdateUserCommand. Until then the server round-trip is a no-op, so carrying a language across devices and minting the locale claim into the refreshed token both need #1381 merged first. Nothing here blocks the other slices.

What is in here

• react-i18next wiring in src/i18n.ts. The chosen language is persisted to the user profile and sent to the API as Accept-Language through apiFetch; variants are canonicalised onto a supported tag before the call, so the API never sees a bare pt.
• en-US and pt-BR catalogs, split per feature namespace, held at strict key and placeholder parity in both directions by tests/i18n/parity.spec.ts — a missing or mis-arged translation fails the build instead of shipping English.
• Language switcher in the topbar, and html[lang] follows the active language through a languageChanged listener. The app previously shipped a static lang="en" that nothing updated, so a Portuguese UI announced itself as English to screen readers and browser translation.
• Formatting stays in the presentation layer (src/lib/format.ts). That is the other half of the framework slice's UI-culture-only decision: the API pins CultureInfo.CurrentCulture to invariant and the app formats numbers, dates and currency itself.
• Impersonation handoff carries locale in the URL. StartImpersonation strips the target's locale claim on purpose, and the two apps normally sit on different origins, so there was no other way to convey it and the API fell through to the dashboard's own browser detection. Harmless on its own: on main nothing reads the parameter until the dashboard slice lands, and this PR's handoff-locale.spec.ts passes with only this half present.

Testing

Everything below is this slice on its own, at main plus these 111 files — not a share of the unsplit branch's totals.

• npm ci, npm run build (tsc -b + vite build), npx tsc -b tsconfig.tests.json and npm run lint: all exit 0.
• Playwright, full suite, one worker: 153 passed, 0 failed, 0 flaky, 0 skipped. That is 136 at the time of the split (135 plus the single-flight test below, i.e. the unsplit branch's count plus one, so nothing was lost in the cut) plus the review follow-ups below. That includes tests/impersonation/handoff-locale.spec.ts, which passes with only this half of the handoff present.

Token refresh is single-flight

The server rotates the refresh token on every successful call, so two refreshes overlapping means the second one presents a token the server has already spent: it gets a 401. The switcher made that reachable, since it refreshes right after persisting the language. It used to end the session outright; see the first follow-up below for the other half of that fix.

The guard lives inside refreshAccessToken() in clients/admin/src/lib/api-client.ts rather than at any one call site, because three paths reach it — the 401 retry in apiFetch, session bootstrap, and the switcher — and any two overlapping is enough. tests/i18n/switcher.spec.ts drives two quick language switches and asserts one refresh request and a session that survives.

src/Directory.Packages.props

One backend file in a React PR, which needs explaining. template-smoke.yml triggers on paths: clients/** and runs dotnet build on the scaffolded solution, and .template.config/template.json does not exclude src/Tests/** — so a front-end-only PR still restores the full package graph and hits NU1903 / GHSA-q939-rpr3-3284 on SSH.NET 2025.1.0, pulled transitively by Testcontainers. That advisory fails restore on main too, re-verified today at 3f2959e6.

What that file carries is the Testcontainers and SourceLink bumps, byte-identical to #1378, so both stay mergeable in either order and this copy can be dropped once #1378 lands. The explicit SSH.NET pin it used to carry is gone: Testcontainers 4.14.0 already depends on the patched version. See the note at the end.

Notes

• The topbar's language hydration stops once the user chooses a language in-session, guarding against a stale profile save echoing the old locale back. That guard has no regression test: reproducing it needs an in-mount profile refetch driven through the Settings form, and the click races the language-change re-render (element detached from the DOM). Three distinct approaches, then stopped rather than paper over it with retries or a longer timeout. The underlying lost update on PUT /identity/profile is tracked in #1359, where the ponytail: comments in the topbar point.
• SignalR does not carry the app locale: the hub client builds its own requests instead of going through apiFetch, so Accept-Language on the negotiate is the browser's. Applies to every session, not just impersonation. (An earlier version of this line claimed handoff-locale.spec.ts named the channel explicitly. It does not — the spec only asserts the handoff URL parameters. Corrected rather than left standing.)

Docs (Golden Rule #10)

fullstackhero/docs#238, kept as a single PR covering all four slices — internationalization.mdx is one page whose sections map across the split. The Frontend (admin and dashboard) section is this slice and the dashboard one: catalogs, language detection and normalization, Accept-Language, the switcher and locale-aware formatting. That PR should merge after the last of the four, so the page never describes code that is not on main yet.

Review follow-ups

An independent review of this slice found one P1 and a few smaller things. All are fixed here:

• Choosing a language could end the session. The single-flight stopped two concurrent refreshes
  from racing, but one failed refresh was still enough on its own: refreshAccessToken() called
  tokenStore.clear() on any non-ok response, so a refresh token that had been revoked, rotated in
  another tab or dropped by a reseed signed the operator out for picking a language. Clearing the
  session now belongs to the callers that know the request needed auth (the 401 retry in apiFetch
  and the boot probe in AuthProvider); the switcher reports the failure instead of swallowing it.
  tests/i18n/switcher.spec.ts covers the single-switch case alongside the double-switch one.
• A failed save was invisible. The language mutation had an onSuccess and no onError, so a
  rejected PUT /identity/profile left the UI switched with nothing to tell the user the choice was
  not stored. It now raises a toast.
• Catalog parity now covers interpolation, not just keys. A translation that drops or renames
  {{var}} renders the placeholder as literal text and no key is missing, so the old gate passed.

Second round

A second independent review found a P1 this slice introduced:

• Approving a top-up printed status.invoiced in the badge. The label key is built from the
  value the API sends, and the catalog had neither status.invoiced nor status.cancelled — while
  it did have status.approved, a status the backend never emits. On main that badge printed the
  raw enum name, so this slice turned something readable into a raw key, on the primary action of the
  screen. The TS union and the status filter carried the same phantom value, so both now mirror
  TopupRequestStatus in Modules.Billing.Contracts.
• Two safety nets, because catalog parity structurally cannot see run-time keys (both locales can
  be missing the same key and still match): parseMissingKeyHandler degrades a missing key to its
  last segment and warns in development, and tests/i18n/status-keys.spec.ts reads the members
  straight out of the backend enums and asserts each resolves in both catalogs. Mutation-checked.
• tests/i18n/i18n.spec.ts read the header off a variable its own route handler assigns, but
  waitForRequest resolves at dispatch, before the handler runs. It reads the resolved request now.
• The deprecated NAV_ITEMS export is gone. Dead since the nav moved to sections/topNavTop
  (no importer in src/ or tests/), and it carried hardcoded English labels that would have
  shipped untranslated the moment anyone imported it.

Infra carve-outs, corrected after review. Two things in the out-of-topic hunks were wrong and
are fixed on the branch:

• The MinIO carve-out only moved minio/minio to quay.io. minio/mc is gone from Docker Hub too
  (hub.docker.com/v2/repositories/minio/mc/ answers 404) and it is what minio-init runs, so both
  dotnet run --project src/Host/FSH.Starter.AppHost and docker compose up died on the pull and the
  fsh bucket was never created. Now pinned to the same quay tag #1388 uses.
• The SSH.NET pin is gone: it pinned nothing. Its own comment claimed bumping Testcontainers
  does not help, but 4.14.0 — which this branch also carries — declares SSH.NET >= 2026.0.0.
  Measured rather than argued: with the pin removed, dotnet restore src/FSH.Starter.slnx --force
  reports zero NU1902/NU1903 and exits 0. (The MessagePack pin next to it stays; removing that one
  does bring its advisory straight back.)

With both applied, deploy/docker/docker-compose.yml and src/Directory.Packages.props are now
genuinely byte-identical to #1388 (git diff --exit-code, checked today), which the earlier claim
was not.

Second review round.

The role detail screen rendered eight group headings, eight blurbs and thirty-four permission
rows straight out of PERMISSION_CATALOG, all English literals: a pt-BR operator opening a role
read a translated shell wrapped around fifty English strings, the largest untranslated surface
left in the app. Each group carries a stable key now, the English text stays in the file as the
fallback, and the screen resolves through the roles catalog.
tests/i18n/status-keys.spec.ts gates it by resolving the permission constants the way the app
does at run time (the catalog holds the permission value, Permissions.Users.Create, not the
identifier it is written with) and asserting every group, blurb and entry exists in both locales.

Seven call sites formatted dates with toLocaleString() and friends, which follow the browser,
not the app: a browser in en-US showed 5/23/2026, 10:00:00 AM beside Portuguese labels.
format.ts gains formatDateTime/formatTime and the call sites go through resolveLocale.
The impersonation card's "started … · expires …" was hardcoded English prose; it is a key now.

Three tests that could not fail, all named in review: format.spec.ts passed an explicit locale
in all nine assertions, so resolveLocale (the branch every production call takes) was never
exercised; html[lang] had no assertion at all while the PR claimed screen readers now see the
real language; and i18n.spec.ts read the Accept-Language header off a variable its own route
handler assigns, but waitForRequest resolves at dispatch, before the handler runs. It reads the
resolved request now.

And one real defect in the fallback this PR introduced. parseMissingKeyHandler took only
the key and returned its capitalized last segment. i18next calls that handler for a missing key
whether or not the call site passed a defaultValue, and the handler's return value is what
renders, so every t(key, { defaultValue }) in the app was being degraded to a truncation of its
own key. Measured against the installed i18next (26.3.6) before the fix:
t("perm.entry.Permissions.Users.Create", { defaultValue: "Create users" }) returned "Create".
The two rules (a caller's fallback wins, otherwise degrade to the last segment) moved to
lib/i18n-fallback.ts, and tests/i18n/missing-key.spec.ts drives them through a real i18next
instance rather than re-implementing the contract. Reverting the guard turns it red.

Third round: numbers, plurals and the upload errors.

Counts went into the string raw. {{count}} and the named count placeholders interpolate the
number with no formatter, so a Portuguese UI read "1234" beside currency and dates on the same
screen that were correctly grouped. Every count (it is the plural selector, so always numeric)
and the named ones, checked one at a time, go through i18next's number formatter now. Two are
deliberately left alone: the files dropzone interpolates already formatted byte sizes, and the
activity page pre-formats its own count.

EntityPageHeader rendered its count chip as `${unit}s`, an English pluralization rule
applied to every language, and four pages passed the unit as an English literal. "organização" +
"s" is not a word. It takes the unit.* plural keys now, the way clients/dashboard's header
already did, with the token typed as a union so an already translated word cannot be handed to it
and render as a missing key.

Upload failures reached the user in English: cancel, transport failure, a rejected PUT, a blocked
extension, an oversize file. They were prose built inside the hook and in module-scope XHR
handlers. They raise an UploadError carrying a catalog key now, and one exported resolver turns
it into text wherever it is shown.

The new format.spec.ts case asserts both halves of the chip on a real list under pt-BR
(1.234 organizações): reverting the formatter or the plural keys turns it red.

One content change rode along with the plural keys and was not called out at the time: the
notifications inbox chip counted "N items" and now counts "N notificações" / "N notifications".
The page was passing unit="item" to a header that appended an "s"; moving to the typed unit
union meant naming what is actually being counted, and unit="notification" is that. The unit is
a deliberate wording change, not a side effect of the formatter.

Fourth round: the three that were declared rather than fixed.

The language detector kept i18next's default i18nextLng storage key. Every other value this app
persists is namespaced (fsh.admin.accessToken, fsh.admin.theme,
fsh.admin.sidebar.collapsed), and the bare key is claimed by both apps on a shared origin and by
any other i18next app deployed beside them. It is fsh.admin.lng now. The migration cost is one
session: a returning user's old value is not read, so the first paint after deploy falls to the
browser locale or the deployment default, and the profile hydrate then restores User.Locale.

format.ts reactivity turned out to hold, and now has a gate that says why rather than an
assurance that it probably does. resolveLocale reads i18n.language when the formatter runs,
so a date formatted on a previous render keeps its locale until something re-renders the
component; nothing in format.ts subscribes to languageChanged. What makes the switch reach a
mounted list is that every component in this app that formats also calls useTranslation (checked
across all of src), and that subscription is easy to drop in a refactor with no test noticing.
The new format.spec.ts case renders an invoice date under en-US, drives the real switcher to
pt-BR, and asserts the same list now reads 01 de mai. de 2026 with the list read exactly once.
Freezing resolveLocale to the language captured at module load turns it red.

Upload-error localization now has a gate of its own: tests/i18n/upload-errors.spec.ts drives the
real avatar picker on /settings/profile under ?culture=pt-BR through a storage PUT that never
connects, one the bucket rejects with a 403, and a presign that never leaves the browser. The 403
case asserts the interpolated {{status}}, not just that some catalog string rendered. Writing it
found one more English string on that path: describeUploadError returned e.message for any
plain Error, and apiFetch does not wrap fetch, so a presign that never reached the API
surfaced as the browser's own TypeError("Failed to fetch") ahead of the localized fallback the
caller had already passed in. That branch logs the original for diagnosis and returns the catalog
string now; restoring return e.message turns the third case red.

The one item left deliberately as-is is the Playwright assertion budget. expect.timeout is
10 s rather than the 5 s default, which aligns it with the action (10 s) and navigation (15 s)
budgets already in this config: every test ends in a toBeVisible, and under CPU contention the
first paint of a lazy route lands past 5 s while staying well inside the other two. It is a wait
budget, not a correctness threshold, and it is flagged here so it can be vetoed rather than
discovered.